PI: Dr. Thomas Girke, professor at Department of Botany and Plant Sciences, University of California, Riverside (thomas.girke@ucr.edu)
Maintainer: Jianhai Zhang (jzhan067@ucr.edu; zhang.jianhai@hotmail.com)
This R package spatialHeatmap is used for interactive visualisation as long as a data matrix and an associated SVG image are provided. This tutorial is specifically designed for how to make an SVG image and link it with the data matrix. The tutorial requires a png image, where regions can be painted by different colours, a data matrix, the SVG editor Inkscape, and optionally the image editor GIMP. The png image is the template to make the SVG image while the data matrix is used to fill different regions in the image. Inkscape is used to associate the SVG image with the data matrix and GIMP is optionally used to facilitate making the SVG image.
In the following, the tutorial is given with a gene expression matrix and an associated root tissue image in SVG format as an example, which is just a basic example for users to start. All the files used in this tutorial can be downloaded here (download an SVG image: click the image, right-click, select “Save image as…”; download a PNG image: click the image, click “Download”, right-click, select “Save image as…”; download a TXT file: click the file, click “Raw”, right-click, select “Save as…”.).
Users are advised to pay enough attention to the bold text below, because it can prevent common errors when creating the SVG images.
In the gene expression matrix, the row and column names are usually gene IDs and sample/conditions, respectively. The sample/condition names MUST be fomatted this way: a sample name is followed by double underscore then the condition, such as “stele__140mM_48h" (Geng et al. 2013), where stele is the sample and 140mM_48h is the condition. One column of meta data (e.g. gene annotation) can also be included in parallel with sample/condition at the end. In the column names of sample/condition and meta data, only letters, digits, single underscore, dots are allowed. Not all samples in the matrix necessarily need to be present in the svg image, and vice versa. Only samples present in the svg image are recognised and coloured. The example of partial gene expression matrix is shown below (Y. Xie 2014; Zhu 2019; Dowle and Srinivasan 2018).
If the contour in the png image is not clear, GIMP can generate low-quality SVG images, so in this case one can draw the blank SVG image with Inkscape by using the png as a template. Below is an example of drawing only two polygons.
The drawing method creates accurate SVG images but it is time-consuming, while the GIMP method is faster but it can generate fused polygons. In this tutorial, the root png image has well-separated polygons and clear contours, so GIMP can produce accurate SVG images. Otherwise the resulting SVG images would have mixed and noise polygons. Considering the pros and cons of two methods, the good practice is to use GIMP to extract polygons first then use drawing method to refine it. Below is an example of an SVG image with fused polygons, which is generated by GIMP.
If a large fused polygon needs to be separated, one can use the eraser tool. Drag the fused polygon away from the tissue, select the eraser tool from the left tool bar, then use the eraser to cut the fused polygon into three independent polygons. Select the cut polygons and click “Break Apart” under the “Path” tab at the top, then the three polygons are entirely separated. Place back the three polygons to make the tissue complete.
In the SVG image, each polygon has a unique ID. To display spatial heatmaps, these IDs should be replaced with sample names exactly from gene matrix. No matter how the blank SVG image is created, it should be placed inside a layer before start the following steps .
Users can add text to label tissues. Basically, the text is first typed in with the text tool and then the text object is coverted to paths. Next paths are added into the polygon group of target tissue and filled with the same tissue colour.
To add a pointer, draw a rectangle and convert it to path, fill it with the same style as the target tissue, then move, rotate and resize it.
Clicking anyone of other tissues will group the text, pointer, and epidermis together, which can be confirmed by dragging epidermis to see they are moving together.
The process of making SVG image and linking it with data matrix is error-prone, if errors arise in the Shiny app, such as some tissues are missing, then users are advised to double check the bold text above, which can prevent most common errors.
anatomybodysystem.com. 2017. “HEAD ANATOMY.” http://anatomybodysystem.com/lateral-view-of-the-brain-labeled/lateral-view-of-the-brain-labeled-brain-diagram-and-label-anatomy-body-list/.
Dowle, Matt, and Arun Srinivasan. 2018. Data.table: Extension of ‘Data.frame‘. https://CRAN.R-project.org/package=data.table.
epilepsyresearch. 2017. “The Hippocampus: What Is It?” https://www.epilepsyresearch.org.uk/the-hippocampus-what-is-it/.
Geng, Yu, Rui Wu, Choon Wei Wee, Fei Xie, Xueliang Wei, Penny Mei Yeen Chan, Cliff Tham, Lina Duan, and José R Dinneny. 2013. “A Spatio-Temporal Understanding of Growth Regulation During the Salt Stress Response in Arabidopsis.” Plant Cell 25 (6): 2132–54.
Mustroph, Angelika, M Eugenia Zanetti, Charles J H Jang, Hans E Holtan, Peter P Repetti, David W Galbraith, Thomas Girke, and Julia Bailey-Serres. 2009. “Profiling Translatomes of Discrete Cell Populations Resolves Altered Cellular Priorities During Hypoxia in Arabidopsis.” Proc Natl Acad Sci U S A 106 (44): 18843–8.
Xie, Yihui. 2014. “Knitr: A Comprehensive Tool for Reproducible Research in R.” In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC. http://www.crcpress.com/product/isbn/9781466561595.
Zhu, Hao. 2019. KableExtra: Construct Complex Table with ’Kable’ and Pipe Syntax. https://CRAN.R-project.org/package=kableExtra.